put "Now performing some time-consuming operation." into promptString
Progress 1,promptString
repeat with i=1 to 100
Progress 2,i
wait 3
end repeat
--wait 1 seconds
Progress 3
end mouseUp
-- part contents for background part 13
----- text -----
41
-- part contents for background part 30
----- text -----
XCMD
-- part contents for background part 2
----- text -----
Progress
-- part contents for background part 3
----- text -----
Up until now, the only method of providing visual feed-back to the user during time intensive operations was to do such things as animate the cursor or plug "update" comments into the message box during the execution of time-consuming scripts.
Progress XCMD provides a much more elegant alternative for providing visual feed-back that everything is proceeding normally.
It displays a dialog containing a graphic display with a "diamond" symbol that moves along a scale to indicate "Percent Complete". The dialog box contains your prompt string as to what is going on and can be positioned anywhere on the screen
(it is centered on the card window by default).
Progress XCMD took a certain amount of effort to create, get functioning and debugged. For those of you who write monster scripts this external command will go a long way toward helping you create a product that looks very polished.
If Progress XCMD is useful to you and you wish to use it, please feel free to use it. I only ask for a $5 registration to support the development of more XCMDs and XFCNs. Believe me, I have more wonderous external commands up my sleeve, and it is based on the support of other users that these things get done.
Send $5 to
Jay Hodgdon
587 Cutwater Lane
Foster City, CA 94404
For feedback and bug reports
(God forbid!) I can be reached at:
CIS: 70411,63
GEnie: JHodgdon
MacNet: HodgdonJ
-- part contents for background part 10
----- text -----
Syntax:
The dialog is first displayed by this call to the XCMD:
Progress 1, <prompt string>
where <prompt string> contains your comments regarding what is going on:
"Now stripping all non-numbers from the phone book." or "Now locating all occurances of "thou" in Hamlet..."
When Progress XCMD is first called the
"diamond indicator" is initially set to 0.
This form of Progress XCMD can also accept two other OPTIONAL parameters:
This allows you to modify the location of the dialog window by providing a top left point at which the dialog will be placed. If the optional parameters are omitted, the dialog will be centered within the card window's boundaries.
The diamond indicator is then moved along the length of the "Percent Complete" scale by calling:
Progress 2,<indicator location>
within a repeat loop.
The <indicator location> should be a WHOLE number between 0 and 100, as these coorespond to the units on the scale. Use the HyperTalk function ROUND to round fractions to the nearest whole number.
Examples:
round(11.5) returns 11
round(11.51) returns 12
The dialog is finally removed from the screen and disposed of by calling:
Progress 3
To get the diamond to move across the scale you must repeatedly call Progress 2,<indicator location> during the execution of your script. You can imagine doing this in a variety of ways.
Now for more on those global variables:
global ProgressPointer,RemoveProgress
In your HyperTalk script you initially display the Progress dialog by calling "Progress 1,<string>". This first call to the external simply displays the dialog and allocates some memory for the it. In order for the dialog to be subsequently modified (i.e., to have the diamond move along the scale), the pointer to the dialog in memory must be retrieved. This is accomplished by storing the dialog's pointer (between calls to the external) in the HyperTalk global variable "ProgressPointer". You don't have to worry about loading the variable yourself. This business is automatically taken care of when the XCMD is first called.
When you call "Progress 2,<integer>" or "Progress 3", the XCMD recovers the location of the dialog in memory (its pointer) by retrieving the information from "ProgressPointer". You don't have to worry about passing the contents of the global on to the XCMD. In fact, all you need to do is to NOT put anything of your own into the global variable "ProgressPointer", or you will surely bomb your Mac (because you'll confuse the XCMD).
Calling "Progress 2,<integer>" retrieves the pointer to the dialog from the global variable and moves the diamond to the new location on the scale. Calling "Progress 3" retrieves the dialog's pointer, gets rid of the dialog and then disposes of the memory used by the dialog.
You can imagine the consequences of calling Progress 2 or Progress 3 without first having called Progress 1. You would be attempting to modify or dispose of memory used by SOMETHING OTHER than the Progress dialog. Your Mac would crash and burn. In order to prevent you wild and crazy people from doing that, calling Progress 1 also loads a second HyperTalk global variable, called
"RemoveProgress". It sets this variable to TRUE.
Then when you call Progress 2 it will do something only if the global variable RemoveProgress is TRUE. The same goes for Progress 3. It will only attempt to dispose of this memory if RemoveProgress is TRUE and will then set RemoveProgress to FALSE (so that it cannot dispose of memory a second time).
Once again, don't change the variable RemoveProgress on your own unless you like to bomb your Mac.
Last thing:
There is an additional reason for having the second global variable RemoveProgress. If your end user becomes impatient and hits command-. to abort a time-consuming handler, the call to the XCMD "Progress 3", to remove the dialog, probably will not have occured. To prevent the dialog from hanging around after such an abort, put the following idle script in your background or stack:
on idle
global ProgressPointer,RemoveProgress
if RemoveProgress is TRUE then
Progress 3
put FALSE into RemoveProgress
end if
pass idle
end idle
In this situation, RemoveProgress could ONLY be TRUE if someone had aborted a handler in which Progress 1 was called and Progress 3 was not.
The resource components of Progress XCMD are:
XCMD "Progress" ID 2155
DLOG "Working" ID 2155
DITL "Working" ID 2155
PICT "Scale" ID 2155
ICON "Note" ID 2222
cicn "Color Note" ID 2222
The cicn resource is strictly optional. If you have a color monitor the cicn (for color icon) will be displayed in place of an ICON of the same ID number. This is no big deal but my feeling is that any way I can squeeze some color into HyperCard is worth the effort. If you don't have a color monitor this resource is ignored (so it doesn't hurt).
